@thi.ng/vectors
Advanced tools
This project is part of the @thi.ng/umbrella monorepo.
Likely the most comprehensive vector library for TypeScript / JavaScript currently available.
This package provides 600+ largely code generated functions and supporting types to perform vector operations on fixed and arbitrary-length vectors, both packed and strided (i.e. where individual vector components are not successive array elements, for example in SOA memory layouts).
Includes componentwise logic operations for boolean vectors, componentwise comparisons for numeric vectors and componentwise binary ops for signed & unsigned integer vectors.
ArrayLike type can be used as vector containers
(e.g. JS arrays, typed arrays, custom impls). Most functions are
implemented as multi-methods, dispatching to any potentially optimized
versions based on given vector arguments.add
performs vector addition on arbitrary-length vectors, add2, add3,
add4 are the optimized version for fixed-length vectors...null, the vector given as 2nd
argument will be used as output (i.e. for mutation).Vec2/3/4
class wrappers and the
gvec()
proxy (for generic, arbitrary-length vectors). These types behave like
normal arrays (for read/write operations) and are also iterable. A
subset of functions (suffixed with S, e.g.
addS
vs. add) also support striding without the need for extra class
wrappers. This is handled via additional index and stride arguments
for each input/output vector. These functions are only available for
sizes 2 / 3 / 4, though.IRandom interface defined by
@thi.ng/random
to work with custom (P)RNGs. If omitted, the built-in Math.random()
will be used.yarn add @thi.ng/vectors
import * as v from "@thi.ng/vectors";
// immutable vector addition (1st arg is result)
v.add([], [1, 2, 3, 4], [10, 20, 30, 40]);
// [11, 22, 33, 44]
// mutable addition (if first arg is null)
a = [1, 2, 3];
v.add(null, a, a);
// [2, 4, 6]
// multiply-add (o = a * b + c)
v.madd([], [10, 20], [0.5, 0.25], [1, 2]);
// [6, 7]
// multiply-add w/ scalar (o = a * n + b)
v.maddN([], [10, 20], 0.5, [1, 2]);
// [6, 12]
// scalar addition w/ arbitrary length & strided vector
v.addN([], gvec([0, 1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0], 3, 1, 4), 10);
// [11, 12, 13]
v.dist([1, 2], [100, 200]);
// 221.37072977247917
v.distManhattan([1, 2], [100, 200]);
// 297
v.distChebyshev([1, 2], [100, 200]);
// 198
v.mixN([], [1, 2], [10, 20], 0.5);
// [5.5, 11]
v.fromHomogeneous([], [100, 200, 0.5]);
// [200, 400]
v.swizzle4([], [1, 2], 1, 1, 0, 0);
// [ 2, 2, 1, 1 ]
v.hash([1, 2, 3])
// 2383338936
madd and maddN functions has
been updated to be compatible with the OpenCL mad function
madd([], a, b, c): before a + b * c, now: a * b + cmaddN([], a, b, n) => maddN([], a, n, b) (i.e. a * n + b)perpendicularLeft2 => perpendicularCCWperpendicularRight2 => perpendicularCWnormalLeft2/ normalRight2 => normalCCW / normalCWWherever possible, each operation comes in different variations. All fixed size versions use optimized, loop-free implementations.
| Suffix | Description | Example |
|---|---|---|
| none | arbitrary length vector arg(s) | add([], [1,2], [10,20]) |
=> [11,22] | ||
| 2 | 2d vector arg(s) | add2([], [1,2], [10,20]) |
=> [11,22] | ||
| 3 | 3d vector arg(s) | add3([], [1,2,3], [10,20,30]) |
=> [11,22,33] | ||
| 4 | 4d vector arg(s) | add4([], [1,2,3,4], [10,20,30,40]) |
=> [11,22,33,44] | ||
| N2 | 2d vector & scalar | addN2([], [1,2], 10) |
=> [11,12] | ||
| N3 | 3d vector & scalar | addN3([], [1,2,3], 10) |
=> [11,12,13] | ||
| N4 | 4d vector & scalar | addN4([], [1,2,3,4], 10) |
=> [11,12,13,14] | ||
| I | arbitrary len, signed int vec | addI([], [-1,2], [10,-20]) |
=> [9,-18] | ||
| U | arbitrary len, unsigned int vec | addU([], [1,2], [10,20]) |
=> [11,22] | ||
| I2 / I3 / I4 | fixed size signed int vec | bitNotI3([], [10,-20,30]) |
=> [-11,19,-31] | ||
| U2 / U3 / U4 | fixed size signed int vec | bitNotU3([], [10,20,30]) |
=> [4294967285,4294967275,4294967265] | ||
| NI / NU | arbitrary len, signed int vec & scalar | addNI([], [1,-2,3], 10) |
=> [11,8,13] | ||
| NI2 / NI3 / NI4 | fixed size signed int vec & scalar | addNI3([], [1,-2,3], 10) |
=> [11,8,13] | ||
| NU2 / NU3 / NU4 | fixed size unsigned int vec & scalar | addNU3([], [1,2,3], 10) |
=> [11,12,13] | ||
| S2 / S3 / S4 | fixed size strided vec into unstrided | addS2([], [0,1,0,2], [10,0,20,0], 0,1,0, 1,2,2) |
=> [11,22] | ||
| SN2 / SN3 / SN4 | fixed size strided vec & scalar | setSN2([0,0,0,0], 10, 1, 2) |
=> [0,10,0,10] | ||
| C | arbitrary len vec, component wise args | setC([], 1,2,3,4) |
=> [1,2,3,4] | ||
| C2 / C3 / C4 | fixed size vec, component wise args | setC4([], 1,2,3,4) |
=> [1,2,3,4] |
MAX2 / MAX3 / MAX4 - each component +InfinityMIN2 / MIN3 / MIN4 - each component -InfinityONE2 / ONE3 / ONE4 - each component 1ZERO2 / ZERO3 / ZERO4 - each component 0X2 / X3 / X4 - positive X axisY2 / Y3 / Y4 - positive Y axisZ3 / Z4 - positive Z axisW4 - positive W axisset / set2 / set3 / set4setC / setC2 / setC3 / setC4 / setC6setN / setN2 / setN3 / setN4setS / setS2 / setS3 / setS4setSN2 / setSN3 / setSN4copyemptyonezeroswizzle2 / swizzle3 / swizzle4setSwizzle1 / setSwizzle2 / setSwizzle3 / setSwizzle4swapXY / swapXZ / swapYZFunctions to create wrapped (strided) vector instances:
vec2 / vec2nvec3 / vec3nvec4 / vec4ngvecWrap existing vanilla vectors:
asVec2 / asVec3 / asVec4Vanilla vector (array) factories:
oneszeroesvecOfsetVN3 / setVN4setVV4 / setVV6 / setVV9 / setVV16Component wise op with 2 input vectors:
add / add2 / add3 / add4div / div2 / div3 / div4mul / mul2 / mul3 / mul4sub / sub2 / sub3 / sub4fmod / fmod2 / fmod3 / fmod4 (GLSL behavior)mod / mod2 / mod3 / mod4 (JS modulo)pow / pow2 / pow3 / pow4addI / addI2 / addI3 / addI4addU / addU2 / addU3 / addU4divI / divI2 / divI3 / divI4divU / divU2 / divU3 / divU4mulI / mulI2 / mulI3 / mulI4mulU / mulU2 / mulU3 / mulU4subI / subI2 / subI3 / subI4subU / subU2 / subU3 / subU4Component wise op with one input vector and single scalar:
addN / addN2 / addN3 / addN4divN / divN2 / divN3 / divN4mulN / mulN2 / mulN3 / mulN4subN / subN2 / subN3 / subN4neg - same as mulN(out, v, -1)fmodN / fmodN2 / fmodN3 / fmodN4 (GLSL behavior)modN / modN2 / modN3 / modN4 (JS modulo)powN / powN2 / powN3 / powN4addNI / addNI2 / addNI3 / addNI4addNU / addNU2 / addNU3 / addNU4divNI / divNI2 / divNI3 / divNI4divNU / divNU2 / divNU3 / divNU4mulNI / mulNI2 / mulNI3 / mulNI4mulNU / mulNU2 / mulNU3 / mulNU4subNI / subNI2 / subNI3 / subNI4subNU / subNU2 / subNU3 / subNU4Functions for memory mapped, strided vectors (without requiring wrappers):
addS2 / addS3 / addS4divS2 / divS3 / divS4mulS2 / mulS3 / mulS4subS2 / subS3 / subS4addm / addm2 / addm3 / addm4addmN / addmN2 / addmN3 / addmN4addW2 / addW3 / addW4 / addW5madd / madd2 / madd3 / madd4maddN / maddN2 / maddN3 / maddN4subm / subm2 / subm3 / subm4submN / submN2 / submN3 / submN4clampclamp2 / clamp3 / clamp4clampN / clampN2 / clampN3 / clampN4clamp01 / clamp01_2 / clamp01_3 / clamp01_4clamp11 / clamp11_2 / clamp11_3 / clamp11_4max / max2 / max3 / max4min / min2 / min3 / min4cross2cross3orthoNormal3signedArea2dotdot2 / dot3 / dot4dotC4 / dotC6 / dotC8dotS2 / dotS3 / dotS4fit / fit2 / fit3 / fit4fit01 / fit01_2 / fit01_3 / fit01_4fit11 / fit11_2 / fit11_3 / fit11_4mix / mix2 / mix3 / mix4mixN / mixN2 / mixN3 / mixN4mixBilinear / mixBilinear2 / mixBilinear3 / mixBilinear4mixCubicmixQuadraticsmoothStep / smoothStep2 / smoothStep3 / smoothStep4step / step2 / step3 / step4limitmagmagSq / magSq2 / magSq3 / magSq4normalizedistdistSq / distSq2 / distSq3 / distSq4distChebyshev / distChebyshev2 / distChebyshev3 / distChebyshev4distManhattan / distManhattan2 / distManhattan3 / distManhattan4angleBetween2 / angleBetween3angleRatioatan_2 / atan_22 / atan_23 / atan_24 (i.e. Math.atan2(y, x))bisect2degrees / degrees2 / degrees3 / degrees4directionfaceForwardheading / headingXY / headingXZ / headingYZheadingSegment / headingSegmentXY / headingSegmentXZ / headingSegmentYZnormalLeft2 / normalRight2perpendicularLeft2 / perpendicularRight2projectradians / radians2 / radians3 / radians4reflectrefract(Also see rotation matrices provided by @thi.ng/matrices)
rotateAroundAxis3rotateAroundPoint2rotateX \ rotateY \ rotateZcartesian / cartesian2 / cartesian3polar / polar2 / polar3All ops support custom PRNG impls based on the
@thi.ng/random
IRandom interface and use Math.random by default:
jitterrandMinMax / randMinMax2 / randMinMax3 / randMinMax4randNormrandom / random2 / random3 / random4abs / abs2 / abs3 / abs4acos / acos2 / acos3 / acos4asin / asin2 / asin3 / asin4atan / atan2 / atan3 / atan4 (i.e. Math.atan(y / x))ceil / ceil2 / ceil3 / ceil4cos / cos2 / cos3 / cos4cosh / cosh2 / cosh3 / cosh4exp / exp2 / exp3 / exp4floor / floor2 / floor3 / floor4fmod / fmod2 / fmod3 / fmod4 (C / GLSL modulo)fract / fract2 / fract3 / fract4fromHomogeneous / fromHomogeneous3 / fromHomogeneous4invert / invert2 / invert3 / invert4invSqrt / invSqrt2 / invSqrt3 / invSqrt4isInf / isInf2 / isInf3 / isInf4isNaN / isNaN2 / isNaN3 / isNaN4log / log2 / log3 / log4major / major2 / major3 / major4minor / minor2 / minor3 / minor4mod / mod2 / mod3 / mod4 (JS modulo)round / round2 / round3 / round4sign / sign2 / sign3 / sign4sin / sin2 / sin3 / sin4sinh / sinh2 / sinh3 / sinh4sqrt / sqrt2 / sqrt3 / sqrt4sum / sum2 / sum3 / sum4tan / tan2 / tan3 / tan4tanh / tanh2 / tanh3 / tanh4trunc / trunc2 / trunc3 / trunc4wrap / wrap2 / wrap3 / wrap4Functions to transform flat / strided buffers w/ vector operations:
mapV / mapVN / mapVV / mapVVN / mapVVVcomparator2 / comparator3 / comparator4eqDelta / eqDelta2 / eqDelta3 / eqDelta4eqDeltaSeqDeltaArrayArguments are assumed to be signed / unsigned ints. Results will be forced accordingly.
bitAndI / bitAndI2 / bitAndI3 / bitAndI4bitAndU / bitAndU2 / bitAndU3 / bitAndU4bitAndNI / bitAndNI2 / bitAndNI3 / bitAndNI4bitAndNU / bitAndNU2 / bitAndNU3 / bitAndNU4bitNotI / bitNotI2 / bitNotI3 / bitNotI4 (unary)bitNotU / bitNotU2 / bitNotU3 / bitNotU4 (unary)bitOrI / bitOrI2 / bitOrI3 / bitOrI4bitOrU / bitOrU2 / bitOrU3 / bitOrU4bitOrNI / bitOrNI2 / bitOrNI3 / bitOrNI4bitOrNU / bitOrNU2 / bitOrNU3 / bitOrNU4bitXorI / bitXorI2 / bitXorI3 / bitXorI4bitXorU / bitXorU2 / bitXorU3 / bitXorU4bitXorNI / bitXorNI2 / bitXorNI3 / bitXorNI4bitXorNU / bitXorNU2 / bitXorNU3 / bitXorNU4lshiftI / lshiftI4 /lshiftI4 / lshiftI4lshiftU / lshiftU4 /lshiftU4 / lshiftU4rshiftI / rshiftI2 /rshiftI3 / rshiftI4rshiftU / rshiftU2 /rshiftU3 / rshiftU4lshiftNI / lshiftNI4 /lshiftNI4 / lshiftNI4lshiftNU / lshiftNU4 /lshiftNU4 / lshiftNU4rshiftNI / rshiftNI2 /rshiftNI3 / rshiftNI4rshiftNU / rshiftNU2 /rshiftNU3 / rshiftNU4logicAnd / logicAnd2 / logicAnd3 / logicAnd4logicAndN / logicAndN2 / logicAndN3 / logicAndN4 (3rd arg is boolean)logicOr / logicOr2 / logicOr3 / logicOr4logicOrN / logicOrN2 / logicOrN3 / logicOrN4 (3rd arg is boolean)logicNot / logicNot2 / logicNot3 / logicNot4every / every2 / every3 / every4some / some2 / some3 / some4All resulting in boolean vectors:
lt / lt2 / lt3/ lt4lte / lte2 / lte3/ lte4gt / gt2 / gt3/ gt4gte / gte2 / gte3/ gte4eq / eq2 / eq3/ eq4neq / neq2 / neq3/ neq4hashcompile / compileG / compileGHOF / compileHOFdefOp / defOpS / defFnOp / defHofOpdefMathNOp / defMathOpvopFor more information about the code generator see:
© 2018 Karsten Schmidt // Apache Software License 2.0
FAQs
Optimized 2d/3d/4d and arbitrary length vector operations, support for memory mapping/layouts
The npm package @thi.ng/vectors receives a total of 1,192 weekly downloads. As such, @thi.ng/vectors popularity was classified as popular.
We found that @thi.ng/vectors demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncovered a backdoored typosquat of BoltDB in the Go ecosystem, exploiting Go Module Proxy caching to persist undetected for years.
Security News
Company News
Socket is joining TC54 to help develop standards for software supply chain security, contributing to the evolution of SBOMs, CycloneDX, and Package URL specifications.
Security News
PyPI now allows maintainers to archive projects, improving security and helping users make informed decisions about their dependencies.